Configuring Movie Data Export Components9

Your component may provide one or more configuration functions. These functions allow applications to configure your component before the Movie Toolbox calls your component to start the export process. Note that applications may call these functions directly.

All of these functions are optional. If your component receives a request that it does not support, you should return the badComponentSelector error code. In addition, your component should work properly even if none of these functions is called.

These functions address a variety of configuration issues. Applications can retrieve additional data from your component by calling the MovieExportGetAuxiliaryData function.

Applications can specify a progress function for use by your component by calling the MovieExportSetProgressProc function.

Applications can instruct your component to display its user dialog box by calling the MovieExportDoUserDialog function.

MovieExportSetProgressProc

The MovieExportSetProgressProc function allows an application to assign a movie progress function.



 
pascal ComponentResult MovieExportSetProgressPro

                                          (MovieImportComponent ci, 

                                         MovieProgressUPP proc, 

                                         long refcon);

ci: Identifies the application's connection to your movie data export component.
proc: Contains a pointer to the application's movie progress function. See the chapter "Movie Toolbox" in Inside Macintosh: QuickTime for a complete description of the interface supported by movie progress functions. If this parameter is set to nil , the application is removing its progress function. In this case, your component should stop calling the progress function.
refcon: Specifies a reference constant. Your component should pass this constant back to the application's progress function whenever you call that function.

DESCRIPTION

Some data export operations may be time-consuming, and application developers may therefore choose to display progress information to the user. Your component provides this information to an application's progress function. As your component processes an export request, you should call the progress function occasionally in order to report on the progress of the operation. Use a progress code of progressOpExportMovie . The application can then present this information to the user.

These progress functions must support the same interface as Movie Toolbox progress functions. That interface is discussed in the chapter "Movie Toolbox" in Inside Macintosh: QuickTime . Note that this interface not only allows you to report progress to the application, but also allows the application to cancel the request.

RESULT CODE

badComponentSelector

0x80008002

Function not supported

MovieExportGetAuxiliaryData

The MovieExportGetAuxiliaryData function allows an application to retrieve additional data from your component. This additional data may be created during the data export process.



 
pascal ComponentResult MovieExportGetAuxiliaryData

                                          (MovieImportComponent ci,

                                         Handle dataH, 

                                         OSType *handleType);

ci: Identifies the application's connection to your movie data export component.
data: Contains a handle that is to be filled with the additional data. Your component should resize this handle as appropriate. Your component is not responsible for disposing of this handle.
handleType: Contains a pointer to the type of data you place in the handle specified by the data parameter.

DESCRIPTION

The MovieExportGetAuxiliaryData function allows an application to retrieve additional data that is generated during the data export process. The application may then use the data as appropriate. Your component may create this data in cases where the target data type cannot accommodate all of the converted data. For example, if your component exports data into 'TEXT' handles or files, you might choose to preserve associated style information for that text. However, 'TEXT' resources cannot store that style information. You could save that style information in a 'styl' handle and allow an application to retrieve it after the conversion.

Your component should expect the application to call this function after the export process ends.

RESULT CODE

badComponentSelector

0x80008002

Function not supported

MovieExportDoUserDialog

The MovieExportDoUserDialog function allows an application to request that your component display its user dialog box.



 
pascal ComponentResult MovieExportDoUserDialog 

                                         (MovieImportComponent ci, 

                                          const FSSpec *theFile,

                                          Handle theData,

                                          Boolean *canceled);

ci: Identifies the application's connection to your movie data export component.
theFile: Contains a pointer to a valid file specification. If the export request pertains to a file, the application must specify the destination file with this parameter and set the parameter theData to nil . If the request is for a handle, this parameter is set to nil .
theData: Contains a handle to receive the converted data. If the export request pertains to a handle, the application must specify the destination handle with this parameter, and set the parameter theFile to nil . If the request is for a file, this parameter is set to nil .
canceled: Contains a pointer to a Boolean value. Your component should set this Boolean value to reflect whether the user cancels the dialog box. If the user cancels the dialog box, set the Boolean value to true . Otherwise, set it to false .

DESCRIPTION

Your movie data export component may support a user dialog box that allows the user to configure an export operation. For components that support such a dialog box, the MovieExportDoUserDialog function allows an application to tell you when to display the dialog box to the user.

If your component supports a user dialog box, be sure to set the hasMovieExportUserInterface flag in your component's componentFlags field.

RESULT CODE

badComponentSelector

0x80008002

Function not supported